NAME¶

rpmem_create(), rpmem_open(), rpmem_set_attr(), rpmem_close(), rpmem_remove() - most commonly used functions for remote access to persistent memory

SYNOPSIS¶

#include <librpmem.h>
RPMEMpool *rpmem_create(const char *target, const char *pool_set_name,
    void *pool_addr, size_t pool_size, unsigned *nlanes,
    const struct rpmem_pool_attr *create_attr);
RPMEMpool *rpmem_open(const char *target, const char *pool_set_name,
    void *pool_addr, size_t pool_size, unsigned *nlanes,
    struct rpmem_pool_attr *open_attr);
int rpmem_set_attr(RPMEMpool *rpp, const struct rpmem_pool_attr *attr);
int rpmem_close(RPMEMpool *rpp);
int rpmem_remove(const char *target, const char *pool_set_name, int flags);

DESCRIPTION¶

The rpmem_create() function creates a remote pool on a given target node, using pool set file pool_set_name to map the remote pool. pool_set_name is a relative path in the root config directory on the target node. For pool set file format and options see poolset(5). pool_addr is a pointer to the associated local memory pool with size pool_size. Both pool_addr and pool_size must be aligned to the system's page size (see sysconf(3)). The size of the remote pool must be at least pool_size. See REMOTE POOL SIZE, below, for details. nlanes points to the maximum number of lanes which the caller is requesting. Upon successful creation of the remote pool, *nlanes is set to the maximum number of lanes supported by both the local and remote nodes. See LANES, below, for details. The create_attr structure contains the attributes used for creating the remote pool. If the create_attr structure is not NULL, a pool with internal metadata is created. The metadata is stored in the first 4096 bytes of the pool and can be read when opening the remote pool with rpmem_open(). To prevent user from overwriting the pool metadata, this region is not accessible to the user via rpmem_persist(). If create_attr is NULL or zeroed, remote pool set file must contain the NOHDRS option. In that case the remote pool is created without internal metadata in it and the entire pool space is available to the user. See rpmem_persist(3) for details.

The rpmem_open() function opens the existing remote pool with set file pool_set_name on remote node target. pool_set_name is a relative path in the root config directory on the target node. pool_addr is a pointer to the associated local memory pool of size pool_size. Both pool_addr and pool_size must be aligned to the system's page size (see sysconf(3)). The size of the remote pool must be at least pool_size. See REMOTE POOL SIZE, below, for details. nlanes points to the maximum number of lanes which the caller is requesting. Upon successful opening of the remote pool, *nlanes is set to the maximum number of lanes supported by both the local and remote nodes. See LANES, below, for details.

The rpmem_set_attr() function overwrites the pool's attributes. The attr structure contains the attributes used for overwriting the remote pool attributes that were passed to rpmem_create() at pool creation. If attr is NULL, a zeroed structure with attributes will be used. New attributes are stored in the pool's metadata.

The rpmem_close() function closes the remote pool rpp. All resources are released on both the local and remote nodes. The remote pool itself persists on the remote node and may be re-opened at a later time using rpmem_open().

The rpmem_remove() function removes the remote pool with set file name pool_set_name from node target. The pool_set_name is a relative path in the root config directory on the target node. By default only the pool part files are removed; the pool set file is left untouched. If the pool is not consistent, the rpmem_remove() function fails. The flags argument determines the behavior of rpmem_remove(). flags may be either 0 or the bitwise OR of one or more of the following flags:

•

RPMEM_REMOVE_FORCE - Ignore errors when opening an inconsistent pool. The pool set file must still be in appropriate format for the pool to be removed.

•

RPMEM_REMOVE_POOL_SET - Remove the pool set file after removing the pool described by this pool set.

RETURN VALUE¶

On success, rpmem_create() returns an opaque handle to the remote pool for use in subsequent librpmem calls. If any error prevents the remote pool from being created, rpmem_create() returns NULL and sets errno appropriately.

On success, rpmem_open() returns an opaque handle to the remote pool for subsequent librpmem calls. If the open_attr argument is not NULL, the remote pool attributes are returned in the provided structure. If the remote pool was created without internal metadata, zeroes are returned in the open_attr structure on successful call to rpmem_open(). If any error prevents the remote pool from being opened, rpmem_open() returns NULL and sets errno appropriately.

On success, rpmem_set_attr() returns 0. On error, it returns -1 and sets errno appropriately.

On success, rpmem_close() returns 0. On error, it returns a non-zero value and sets errno appropriately.

On success, rpmem_remove() returns 0. On error, it returns a non-zero value and sets errno appropriately.

NOTES¶

SEE ALSO¶

rpmem_persist(3), sysconf(3), limits.conf(5), libpmemobj(7), librpmem(7) and <http://pmem.io>